![Introducing Enhanced Alert Actions and Triage Functionality](https://cdn.sanity.io/images/cgdhsj6q/production/fe71306d515f85de6139b46745ea7180362324f0-2530x946.png?w=800&fit=max&auto=format)
Product
Introducing Enhanced Alert Actions and Triage Functionality
Socket now supports four distinct alert actions instead of the previous two, and alert triaging allows users to override the actions taken for all individual alerts.
webidl-conversions
Advanced tools
Package description
The webidl-conversions npm package is used to convert JavaScript values to WebIDL types, as specified in the WebIDL specification. It is often used in the context of web development when implementing interfaces defined in WebIDL that need to interact with JavaScript code.
Converting basic types
Converts a JavaScript string to a WebIDL 'long' type.
const conversions = require('webidl-conversions');
let myValue = '123';
let convertedValue = conversions.long(myValue);
Converting with options
Converts a JavaScript string to a WebIDL 'long' type with clamping enabled, which means the value will be clamped to the nearest allowed value if it's out of range.
const conversions = require('webidl-conversions');
let myValue = '123';
let convertedValue = conversions.long(myValue, { clamp: true });
Handling nullable types
Converts a null value to a WebIDL 'DOMString' type, treating null as an empty string.
const conversions = require('webidl-conversions');
let myValue = null;
let convertedValue = conversions.DOMString(myValue, { treatNullAsEmptyString: true });
Heya-unify is a library for unifying JavaScript values with type descriptions. It is similar to webidl-conversions in that it deals with type conversions, but it is more focused on unification patterns and not specifically on WebIDL types.
TypeScript is a superset of JavaScript that adds static types. While not a direct alternative to webidl-conversions, it provides a type system that can help ensure that values match expected types at compile time, rather than performing runtime conversions.
Readme
This package implements, in JavaScript, the algorithms to convert a given JavaScript value according to a given Web IDL type.
The goal is that you should be able to write code like
"use strict";
const conversions = require("webidl-conversions");
function doStuff(x, y) {
x = conversions["boolean"](x);
y = conversions["unsigned long"](y);
// actual algorithm code here
}
and your function doStuff
will behave the same as a Web IDL operation declared as
void doStuff(boolean x, unsigned long y);
This package's main module's default export is an object with a variety of methods, each corresponding to a different Web IDL type. Each method, when invoked on a JavaScript value, will give back the new JavaScript value that results after passing through the Web IDL conversion rules. (See below for more details on what that means.) Alternately, the method could throw an error, if the Web IDL algorithm is specified to do so: for example conversions["float"](NaN)
will throw a TypeError
.
Each method also accepts a second, optional, parameter for miscellaneous options. For conversion methods that throw errors, a string option { context }
may be provided to provide more information in the error message. (For example, conversions["float"](NaN, { context: "Argument 1 of Interface's operation" })
will throw an error with message "Argument 1 of Interface's operation is not a finite floating-point value."
) Specific conversions may also accept other options, the details of which can be found below.
Conversions for all of the basic types from the Web IDL specification are implemented:
any
void
boolean
{ clamp, enforceRange }
as a second parameterfloat
, unrestricted float
double
, unrestricted double
DOMString
, which can additionally be provided the boolean option { treatNullAsEmptyString }
as a second parameterByteString
, USVString
object
Additionally, for convenience, the following derived type definitions are implemented:
ArrayBufferView
BufferSource
DOMTimeStamp
Function
VoidFunction
(although it will not censor the return type)Derived types, such as nullable types, promise types, sequences, records, etc. are not handled by this library. You may wish to investigate the webidl2js project.
long long
typesThe long long
and unsigned long long
Web IDL types can hold values that cannot be stored in JavaScript numbers, so the conversion is imperfect. For example, converting the JavaScript number 18446744073709552000
to a Web IDL long long
is supposed to produce the Web IDL value -18446744073709551232
. Since we are representing our Web IDL values in JavaScript, we can't represent -18446744073709551232
, so we instead the best we could do is -18446744073709552000
as the output.
This library actually doesn't even get that far. Producing those results would require doing accurate modular arithmetic on 64-bit intermediate values, but JavaScript does not make this easy. We could pull in a big-integer library as a dependency, but in lieu of that, we for now have decided to just produce inaccurate results if you pass in numbers that are not strictly between Number.MIN_SAFE_INTEGER
and Number.MAX_SAFE_INTEGER
.
What's actually going on here, conceptually, is pretty weird. Let's try to explain.
Web IDL, as part of its madness-inducing design, has its own type system. When people write algorithms in web platform specs, they usually operate on Web IDL values, i.e. instances of Web IDL types. For example, if they were specifying the algorithm for our doStuff
operation above, they would treat x
as a Web IDL value of Web IDL type boolean
. Crucially, they would not treat x
as a JavaScript variable whose value is either the JavaScript true
or false
. They're instead working in a different type system altogether, with its own rules.
Separately from its type system, Web IDL defines a "binding" of the type system into JavaScript. This contains rules like: when you pass a JavaScript value to the JavaScript method that manifests a given Web IDL operation, how does that get converted into a Web IDL value? For example, a JavaScript true
passed in the position of a Web IDL boolean
argument becomes a Web IDL true
. But, a JavaScript true
passed in the position of a Web IDL unsigned long
becomes a Web IDL 1
. And so on.
Finally, we have the actual implementation code. This is usually C++, although these days some smart people are using Rust. The implementation, of course, has its own type system. So when they implement the Web IDL algorithms, they don't actually use Web IDL values, since those aren't "real" outside of specs. Instead, implementations apply the Web IDL binding rules in such a way as to convert incoming JavaScript values into C++ values. For example, if code in the browser called doStuff(true, true)
, then the implementation code would eventually receive a C++ bool
containing true
and a C++ uint32_t
containing 1
.
The upside of all this is that implementations can abstract all the conversion logic away, letting Web IDL handle it, and focus on implementing the relevant methods in C++ with values of the correct type already provided. That is payoff of Web IDL, in a nutshell.
And getting to that payoff is the goal of this project—but for JavaScript implementations, instead of C++ ones. That is, this library is designed to make it easier for JavaScript developers to write functions that behave like a given Web IDL operation. So conceptually, the conversion pipeline, which in its general form is JavaScript values ↦ Web IDL values ↦ implementation-language values, in this case becomes JavaScript values ↦ Web IDL values ↦ JavaScript values. And that intermediate step is where all the logic is performed: a JavaScript true
becomes a Web IDL 1
in an unsigned long context, which then becomes a JavaScript 1
.
Seriously, why would you ever use this? You really shouldn't. Web IDL is … strange, and you shouldn't be emulating its semantics. If you're looking for a generic argument-processing library, you should find one with better rules than those from Web IDL. In general, your JavaScript should not be trying to become more like Web IDL; if anything, we should fix Web IDL to make it more like JavaScript.
The only people who should use this are those trying to create faithful implementations (or polyfills) of web platform interfaces defined in Web IDL. Its main consumer is the jsdom project.
FAQs
Implements the WebIDL algorithms for converting to and from JavaScript values
The npm package webidl-conversions receives a total of 67,636,151 weekly downloads. As such, webidl-conversions popularity was classified as popular.
We found that webidl-conversions demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 6 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
Socket now supports four distinct alert actions instead of the previous two, and alert triaging allows users to override the actions taken for all individual alerts.
Security News
Polyfill.io has been serving malware for months via its CDN, after the project's open source maintainer sold the service to a company based in China.
Security News
OpenSSF is warning open source maintainers to stay vigilant against reputation farming on GitHub, where users artificially inflate their status by manipulating interactions on closed issues and PRs.